/*
 * @(#)SessionManager.java	1.20 02/08/21
 *
 * Copyright (c) 1996-2002 Sun Microsystems, Inc.  All rights reserved.
 */

package javax.media.rtp;

import java.io.IOException;
import java.util.Vector;

import javax.media.Controls;
import javax.media.Format;
import javax.media.format.UnsupportedFormatException;
import javax.media.protocol.DataSource;
import javax.media.rtp.rtcp.SourceDescription;

/**
 * The interface implemented by the SessionManager. This is the
 * starting point for creating, maintaining and closing an RTP
 * session.
 * @deprecated This inferface has been replaced with the 
 * RTPManager interface.
 */
public abstract interface SessionManager extends Controls

{
    /** Used to specify an unspecified SSRC for methods which retrieve an
     * SSRC
     */
    public static final long SSRC_UNSPEC = 0;
 

    /**
     * Initializes the session.  Once this method has been called, the
     * session  is "initialized" and this method cannot be called again. <P>
     *
     * @param localAddress Encapsulates the *local* control and data
     * addresses to be used for the session.  If either InetAddress
     * contained in  this parameter is null, a default local address
     * will be chosen; this should be adequate except for multi-homed
     * systems with  more than one IP
     * interface. The ports do not necessarily need to be specified
     * (i.e. they  may be the ANY_PORT constant); RTPSM will pick
     * appropriate ports  in that case. In any case, the fully specified
     * local addresses to be used are returned in this object. <P>
     * Note: The localAddress is the interface and port used by the
     * sending/transmitting threads of the SessionManager. The
     * receiving threads will use the address and port of the RTP
     * session that is supplied in startSession(). 
     *
     * @param defaultSSRC Identifies an SSRC value to use for this
     * participant.   This SSRC value will go out in RTCP listener
     * reports from this participant. 
     * .If the user wishes that RTPSM generate the SSRC, it must use the
     * initSession() call mentioned below.<P>
     *
     * @param defaultSourceDesc An array of SourceDescription
     * objects  containing information to send in RTCP SDES packets
     * for the  local participant.  This information  can be changed by
     * calling setSourceDescription() on the local Participant
     * object.  
     * @param rtcp_bw_fraction The fraction of the session bandwidth
     * that the RTPSM must use when sending out RTCP reports. 
     * @param rtcp_sender_bw_fraction The fraction of the
     * rtcp_bw_fraction that the RTPSM must use to send out RTCP Sender
     * reports from the local participant. The remaining fraction of the
     * rtcp_bw is used for sending out RTCP Receiver reports.  <P>
     *
     * Note : The rtcp_bw_fraction is set to zero for a
     * non-participating observer of this Session. In this case 
     * the application will receive both RTP and RTCP messages, but will
     * not send out any RTCP feedback reports.
     * This is equivalent to setting the outgoing RTP/RTCP
     * bandwidth of this application to zero, implying that this
     * application may NOT send out any data or control streams and can
     * thus not make a call to createSendStream(). If it does, it will
     * receive an exception. Further, this application is NOT considered
     * an Participant since it does not send out any RTCP
     * information. Consequently, this client will NOT appear in the
     * list of Participants for this session.<P>
     *
     * InitSession called a second time or thereafter will return
     * without doing anything, since the session had already been
     * initialized. If parameters to initSession() are different from
     * before, the user must note that  the new parameters will ignored
     * as a result of no action being performed. In this case,
     * the return value is -1
     * indicating no action was taken since initSession had previously
     * been called <P>
     *
     * @return Returns 0 if initSession was executed succesfully and
     * -1 initSession was previously executed.
     * @exception InvalidSessionAddressException This exception is
     * thrown if the local control and data addresses given in
     * parameter localAddress do not belong to one of the localhost
     * interfaces. 
     *
     * @classname SessionAddress
     * @classname SourceDescription
     * <p>
     */
    public int
    initSession( SessionAddress localAddress,
		long defaultSSRC,
		SourceDescription defaultUserDesc[],
		double rtcp_bw_fraction,
		double rtcp_sender_bw_fraction)
	throws InvalidSessionAddressException;
     /**
      * This form of initSession is to be used when the SSRC is to be
      * generated by the RTPSM. In this case, the client allows the
      * underlying implementation to choose an  appropriate SSRC, and
      * the SSRC chosen can be retrieved with getDefaultSSRC(). <P>
      *
      * InitSession called a second time or thereafter will return
      * without doing anything, since the session had already been
      * initialized. If parameters to initSession() are different from
      * before, the user must note that  the new parameters will ignored
      * as a result of no action being performed. In this case, 
      * The return value is -1
      * indicating no action was taken since initSession had previously
      * been called <P>
      *
      * @return Returns 0 if initSession was executed succesfully and
      * -1 initSession was previously executed.
      * 
      * @classname InitSession
      * @exception InvalidSessionAddressException This exception is
      * thrown if the local control and data addresses given in
      * parameter localAddress do not belong to one of the localhost
      * interfaces. 
      *
      * @classname SessionAddress
      * @classname SourceDescription
      * <p>
      */
    public int
    initSession( SessionAddress localAddress,
		SourceDescription defaultUserDesc[],
		double rtcp_bw_fraction,
		double rtcp_sender_bw_fraction)
	throws InvalidSessionAddressException;
    /**
     * This method starts the session, causing RTCP reports to
     * generated and  callbacks to be made through the
     * SessionListener  interface. This method must be called after
     * session initialization and prior to the creation of any streams
     * on a session.  A valid destination address is required
     * even for sessions that will have no sending streams so that RTCP
     * control  messages can be sent.
     *  <P>
     *
     * @param destAddress The RTP session address which is defined as
     * the address,port combination pair to which data and
     * control  packets  will be sent.  As opposed to the localAddress
     * parameter  specified in initSession,some portions  of this 
     * SessionAddress *must* be specified.This is the Session
     * Address and is defined in the RFC as one network address and a
     * port pair for RTP/RTCP. The RTP ports is even and one lower than
     * the RTCP port.Either of the RTP or RTCP address, port pair must
     * be supplied in destAddress parameter.
     * Note: For multicast sessions, this address will be the
     * multicast address to which data will  be sent. In case of a
     * UNICAST session, you can enter either the IP address of the
     * receiver of data i.e. address to which data is destined OR the IP
     * address of the sender i.e. address to which control packets are
     * to be sent. For broadcast session, this
     * address will be the subnet broadcast address. 
     *
     * @return Returns 0 if startSession was executed succesfully and
     * -1 startSession was previously executed.
     * 
     * @param mcastScope If the destination address specified is an IP
     * multicast  address, this value
     * specifies the ttl of outgoing packets on that address. <P>
     *
     * @param encryptionInfo Encryption information for this
     * session. <P>
     
     * @exception IOException This exception is thrown if the local
     * control and data sockets cannot be opened or if the mulitcast
     * group cannot be joined. 
     *
     * @exception InvalidSessionAddressException This exception is
     * thrown if the Session Address is incomplete in that it
     * cannot be completely deciphered.  
     * @classname SessionAddress
     * @classname EncryptionInfo
     * <p>     
     */
    public int
    startSession(SessionAddress destAddress,
		 int mcastScope,
		 EncryptionInfo encryptionInfo)
	throws  IOException, InvalidSessionAddressException;
    /**
     * This method may be used instead of startSession() above, but only
     * in case of UNICAST sessions. It allows a user to specify
     * distinct port pairs for the two end points of a unicast session
     * only.
     * Note: This feature is not in RFC 1889, but has been added in a later
     * RTP draft.
     * @param localReceiverAddress specifies the RTP session address of the
     * local end point of this unicast session. i.e. the IP
     * address, data/ control port of the local host
     * @param localSenderAddress specifies the local RTP session address that
     * is used for sending out RTP and RTCP packets.
     * @param remoteReceiverAddress The RTP session address of the remote end
     * point of this unicast session. i.e. the IP address,port of the
     * remote host
     * 
     * @exception IOException This exception is thrown if the local
     * control and data sockets cannot be opened.
     *
     * @exception InvalidSessionAddressException This exception is
     * thrown if the Session Address is incomplete in that it
     * cannot be completely deciphered or the addresses supplied are
     * NOT unicast IP addresses.
     * 
     * @return Returns 0 if startSession was executed succesfully and
     * -1 startSession was previously executed.
     * 
     * @classname SessionAddress
     * @classname EncryptionInfo
     * <p>
     */
    public int
    startSession(SessionAddress localReceiverAddress,
		 SessionAddress localSenderAddress,
		 SessionAddress remoteReceiverAddress,
		 EncryptionInfo encryptionInfo)
	throws  IOException, InvalidSessionAddressException;
	/**
     * Adds a SessionListener. A SessionListener will receive
     * events that pertain to the Session as a whole. Currently,
     * these include the NewParticipantEvent and
     * LocalCollisionEvent. Events are notified in the
     * update(SessionEvent) method which must be implemented by all
     * SessionListeners. 
     * @classname SessionListener
     */
    public void
    addSessionListener(SessionListener listener);
    /**
     * Adds a RemoteListener to the session. This listener listens
     * to all remote RTP events. Currently, these include
     * ReceiverReportEvent, ReceiveSenderReportEvent and
     * RemoteCollisionEvent. This interface would be usefuly for an RTCP
     * monitor that does not wish to receive any particular stream
     * transitionEvents but just wants to monitor the session quality
     * and statistics.
     */
    public void
    addRemoteListener( RemoteListener listener);
    /**
     * Adds a ReceiveStreamListener. This listener listens to all the
     * events that notify state transitions for a particular
     * ReceiveStream.
     */
    public void
    addReceiveStreamListener( ReceiveStreamListener listener);
    /**
     * Adds a SendStreamListener. This listener listens to all the
     * events that notify state transitions for a particular
     * SendStream.
     */
    public void
    addSendStreamListener(SendStreamListener listener);
    /**
     * removes a SessionListener
     * @classname SessionListener
     */ 
    public void
    removeSessionListener(SessionListener listener);
    /**
     * removes a RTPRemoteListener
     * @classname RTPRemoteListener
     */ 
    public void
    removeRemoteListener( RemoteListener listener);
    /**
     * removes a ReceiveStreamListener
     * @classname ReceiveStreamListener
     */ 
    public void
    removeReceiveStreamListener( ReceiveStreamListener listener);
    /**
     * removes a SendStreamListener
     * @classname SendStreamListener
     */ 
    public void
    removeSendStreamListener(SendStreamListener listener);
    /**
     * Returns the default SSRC for this session.  Returns SSRC_UNSPEC
     * if the  session has not yet been initialized. <P>
     */
    public long
    getDefaultSSRC();  
    /**
     * Returns a Vector of all the remote participants in the
     * session.This vector is simply a snapshot of the current state in
     * the SessionManager.The SessionListener interface can be
     * used to get notified of additional participants for the
     * Session. <P>
     */
    public Vector
    getRemoteParticipants();
    /**
     * Returns a vector of all the active (data sending)
     * participants. These participants may be remote and/or the local participant.
     */
    public Vector
    getActiveParticipants();
    /**
     * Returns all the passive participants. These participants will
     * include the local participant and some remote participants that
     * do not send any data.
     */
    public Vector
    getPassiveParticipants();
    /**
     * Retrieves the local participant
     */
    public LocalParticipant
    getLocalParticipant();
    /**
     * Returns all the participants of this session.
     */
    public Vector
    getAllParticipants();
    /** Returns the ReceiveStreams created by the
     * SessionManager. These are streams formed when the RTPSM
     * detects a new source of RTP data. 
     * ReceiveStreams returned are a snapshot of the current state in the
     * RTPSesionManager and the ReceiveStreamListener interface may be used
     * to get notified of additional streams.
     */   
    public Vector
    getReceiveStreams();
    /** Returns the SendStreams created by the
     * SessionManager.
     * SendStreams returned are a snapshot of the current state in the
     * RTPSesionManager and the SendStreamListener interface may be used
     * to get notified of additional streams.
     */   
    public Vector
    getSendStreams();

    /** Returns the RTPStream created by the SessionManager that
     * has the same SSRC as the filterssrc. If no stream with the
     * filterssrc exits, null is returned. <p>
     *
     * Note: the return type for this method has been changed from long
     * to int.
     */
    public RTPStream
    getStream(long filterssrc);
    /**
     * Allows the user to retrieve the multicast TTL set for this
     session.
     */
    public int
    getMulticastScope();
    /**
     * Sets the IP Multicast TTL for this session. <P>
     *
     * @param multicastScope Specifies the new multicast scope for the
     * session. A multicastScope less than 1 defaults to a scope of 1
     * set for the session. <P>
     */    
    public void
    setMulticastScope(int multicastScope);
    /**
     * Informs RTP that the application is ready to terminate the
     * session. All open streams will be closed after this call
     * completes, and the  object implementing this  interface is no longer
     * useful as an SessionManager. <P>
     * 
     * @param reason A string that RTCP will send out to other
     * participants  as the reason the local participant  has quit the
     * session.This RTCP packet will go out with  the default SSRC of the
     * session. If supplied as null, a default reason will be supplied by RTP.  <P>
     */
    public void
    closeSession(String reason);
    /**
     * This function can be used to generate a CNAME using the scheme
     * described in RFC1889. This function is provided in order to facilitate CNAME
     * generation prior to actual stream creation. <P>
     *
     * @return The generated CNAME. <P>
     */
    public String
    generateCNAME();
    /**
     * This function can be used to generate a SSRC using the scheme
     * described in RFC1889. This function is provided in order to facilitate SSRC
     * generation prior to actual stream creation, which may be useful for call
     * control functions which need to exchange SSRCs before stream transmission
     * commences.  <P>
     * Note: the return type has been changed from long to int. <P>
     *
     * @return The generated SSRC. <P>
     */
    public long
    generateSSRC();
    /**
     * Method to get the Destination SessionAddress of this SessionManager
     * This will return the data address/port and control address/port
     * that the RTP manager is receiving data/control packets on and
     * sending RTCP packets to. <p>
     */
    public SessionAddress
    getSessionAddress();
    /**
     * Method to get the local SessionAddress  of this
     * SessionManager. This will return the local address and port
     * bound to of the socket which is sending out RTP/RTCP packets. Since the
     * RTPSM does not send out any RTP packets, the destaddress/port
     * field of SessionAddress will not be filled in.
     * Note: current implementations of JDK will return
     * 0.0.0.0/0.0.0.0 for a socket.getLocalAddress() call. 
     *
     */
    public SessionAddress
    getLocalSessionAddress();
    /**
     * This method will provide access to overall data and control
     * messsage reception statistics for this Session. Statistics on
     * data from individual sources is available from method
     * getSourceReceptionStats() of interface ReceiveStream
     * @return The GlobalReceptionStats for this session
     * @classname ReceiveStream
     */
    public GlobalReceptionStats
    getGlobalReceptionStats();
     /**
     * This method will provide access to overall data and control
     * messsage transmission statistics for this Session. Statistics on
     * data from individual sources is available from method
     * getSourceTransmissionStats() of interface SendStream
     * @return The GlobalTransmissionStats for this session
     * @classname SendStream
     */
    public GlobalTransmissionStats
    getGlobalTransmissionStats();
    /**
     * This method is used to create a sending stream within the RTP
     * session. For each time the call is made, a new sending stream
     * will be created. This stream will use the SDES items as entered
     * in the initSession() call for all its RTCP messages. Each stream
     * is sent out with a new SSRC (Synchronisation SouRCe
     * identifier), but from the same participant  i.e. local
     * participant. <BR>
     * 
     * @param ssrc The Synchronisation source identifier to be used when
     * sending out this data stream. Note: Since the ssrc  to be used by
     * the local member is supplied in the initSession() call as well,
     * the first SendStream created will use that ssrc and hence
     * IGNORE the ssrc supplied in createSendStream. Subsequent calls to
     * createSendStream() will use the ssrc supplied as this argument.
     * Use createSendStream (DataSource, int, int) to start a send
     * stream without supplying an SSRC. <BR>
     *
     * @param ds This is the PushOutputDataSource or
     * PullOutputDataSource which is the output datasource of the
     * Processor. This datasource may contain more than one
     * stream. The stream which is used in creating this RTP
     * stream is specified in the next parameter of stream.<BR>
     *
     * @param streamindex The index of the sourcestream from which
     * data is sent out on this RTP stream. An index of 1 would indicate the first
     * sourcestream of this datasource should be used to create the RTP
     * stream. If the index is set to zero, it would indicate a RTP
     * mixer operation is desired. i.e. all the streams of this
     * datasource must be mixed into one single stream from one single
     * SSRC. <BR>
     * 
     * @param packet_interval This is the packetization interval in
     * millisecs that must constitute each RTP packet when it is
     * transmitted over the network. The packetization interval
     * determines the  minimum end-to-end delay; longer packets
     * introduce less  header overhead but higher delay and make packet loss more
     * noticeable. For non interactive applications such as lectures or
     * links with  severe bandwidth constraints, a higher packetization delay may be
     * appropriate. <BR>
     * 
     * If this parameter is supplied as zero, the  
     * packetizer's default packetization interval will be used.<BR>
     *
     * Note: The RTP payload that is used to send this stream is found
     * from the format set on the SourceStream of the datasource
     * supplied. <BR>
     * If the sourcestream has no format set or has a
     * format for which a packetizer plugin cannot be found in the session
     * manager's database, an UnsupportedFormatException will be thrown
     * by the SessionManager. <BR>
     * 
     * Note on PullDataSources supplied to the RTP session manager :
     * In most cases, it is expected that the datasource supplied to the
     * RTP session manager for stream creation would be a
     * PushDataSource. In cases that the datasource is a pulldatasource,
     * it MUST have a format set on its SourceStreams. This is the only
     * way for SessionManger to determine the RTP payload to use in
     * the header of the stream as well as the bitrate to pulldata from
     * this datasource. <BR>
     *
     * @return The SendStream created by the RTP session manager.<BR>
     *    
     * @exception UnsupportedFormatException
     * (javax.media.format.UnsupportedFormatException ). This
     * exception is thrown if the format is not set on the sourcestream
     * or a RTP payload cannot be located for the format set on the
     * sourcestream.
     * @exception SSRCInUseException <BR>
     * This is thrown if the ssrc supplied as the first argument is
     * already in use by another sendstream of this local
     * participant. RTP requires that each sending stream of the same
     * participant in the same session use a different unique SSRC.  <BR>
     *
     * @exception IOException
     * Thrown for two possible reasons which will be specified in the
     * message part of the exception
     * 1) If the session was initiated with zero rtcp_bw_fraction which
     * implied that this participant could not send out any RTP/RTCP
     * data or control messages. i.e. it could not also create any send
     * streams and was just a passive listener for this session.
     * 2) If there was any problem opening the sending sockets 
     * @classname SendStream 
     * 
     */
    public SendStream
    createSendStream(int ssrc,
		     DataSource ds,
		     int streamindex) throws
    UnsupportedFormatException, SSRCInUseException, IOException;
    
    /**
     * This method is the same as the createSendStream(int ssrc,
     * DataSource ds, in t streamindex, int packet_interval) except
     * that the user  need not supply the SSRC of the stream. The SSRC
     * will be  chosen by the SessionManager itself.<BR>
     * 
     * This method is used to create a sending stream within the RTP
     * session. For each time the call is made, a new sending stream
     * will be created. This stream will use the SDES items as entered
     * in the initSession() call for all its RTCP messages. Each stream
     * is sent out with a new SSRC (Synchronisation SouRCe
     * identifier), but from the same participant  i.e. local
     * participant. <BR>
     *
     * @param ds This is the PushOutputDataSource or
     * PullOutputDataSource which is the output datasource of the
     * Processor. This datasource may contain more than one
     * stream. The stream which is used in creating this RTP
     * stream is specified in the next parameter of stream.<BR>
     *
     * @param streamindex The index of the sourcestream from which
     * data is sent out on this RTP stream. An index of 1 would indicate the first
     * sourcestream of this datasource should be used to create the RTP
     * stream. If the index is set to zero, it would indicate a RTP
     * mixer operation is desired. i.e. all the streams of this
     * datasource must be mixed into one single stream from one single
     * SSRC. <BR>
     * 
     * @param packet_interval This is the packetization interval in
     * millisecs that must constitute each RTP packet when it is
     * transmitted over the network. The packetization interval
     * determines the  minimum end-to-end delay; longer packets
     * introduce less  header overhead but higher delay and make packet loss more
     * noticeable. For non interactive applications such as lectures or
     * links with  severe bandwidth constraints, a higher packetization delay may be
     * appropriate. <BR>
     * 
     * If this parameter is supplied as zero, the  
     * packetizer's default packetization interval will be used.<BR>
     *
     * Note: The RTP payload that is used to send this stream is found
     * from the format set on the SourceStream of the datasource
     * supplied. <BR>
     * If the sourcestream has no format set or has a
     * format for which a packetizer plugin cannot be found in the session
     * manager's database, an UnsupportedFormatException will be thrown
     * by the SessionManager. <BR>
     * 
     * Note on PullDataSources supplied to the RTP session manager :
     * In most cases, it is expected that the datasource supplied to the
     * RTP session manager for stream creation would be a
     * PushDataSource. In cases that the datasource is a pulldatasource,
     * it MUST have a format set on its SourceStreams. This is the only
     * way for SessionManger to determine the RTP payload to use in
     * the header of the stream as well as the bitrate to pulldata from
     * this datasource. <BR>
     *
     * @return The SendStream created by the RTP session manager.<BR>
     *    
     * @exception UnsupportedFormatException
     * (javax.media.format.UnsupportedFormatException ). This
     * exception is thrown if the format is not set on the sourcestream
     * or a RTP payload cannot be located for the format set on the
     * sourcestream.
     * @exception IOException
     * Thrown for two possible reasons which will be specified in the
     * message part of the exception
     * 1) If the session was initiated with zero rtcp_bw_fraction which
     * implied that this participant could not send out any RTP/RTCP
     * data or control messages. i.e. it could not also create any send
     * streams and was just a passive listener for this session.
     * 2) If there was any problem opening the sending sockets 
     * @classname SendStream 
     * 
     */
    public SendStream
    createSendStream(DataSource ds,
		     int streamindex) throws
    UnsupportedFormatException, IOException;
    /**
     * This method is used to add a dynamic payload ---> Format
     * mapping in the SessionManager. The SessionManager maintains
     * all static payload numbers and their correspnding Formats as
     * mentioned in the Audio/Video profile document. Using the plugin
     * packethandler interface, a user may plugin his own packetizer or
     * depacketizer to handle RTP streams of a proprietary format using
     * dynamic payload numbers as specified in the AV profile. Before
     * streaming payload of a dynamic nature, a Format object needs to
     * be created for the dynamic payload and associated with a dynamic
     * payload number.
     * @param fmt The Format to be associated with this dynamic
     * payload number.
     * @param payload The RTP payload number
     * @see Format 
     */
    public void
    addFormat(Format fmt,
	      int payload);
  /**
   * This variant of the startSession() method is for starting
   * a session with an empty list of peers. This method is meant to be
   * used to start a multi-unicast session. For more details, please see
   * documentation on multi-unicast sessions.  
   * @param mcastScope if the address in the addPeer() method is a
   * multicast address, the packets are sent out with this ttl.
   * @param encryptionInfo the encryption information to be used in
   * this session.
   * @returns same as other forms of startSession <p>
   */
  public int 
      startSession(int mcastScope, EncryptionInfo encryptionInfo) throws IOException;
  /**
   * Adds a peer to the list of peers.
   * This method can be used when an RTP Session is to be built based on a
   * full mesh of unicast streams between participants (this is called
   * multi-unicast).
   * If there is more than one peer in the list the SessionManager
   * duplicates outbound RTP or RTCP packets.
   * The duplicates are addressed to each peer in the list of peers.
   * <p>If the peer is already in the list the method call is ignored.
   * <p>[Note: The notion of a list of peers can be readily extended
   * to contain multicast addresses as well.
   * This would enable hybrid multicast and multi-unicast RTP Sessions.]
   *
   * @param peerAddress The unicast address pair (RTP transport address,
   RTCP transport address) of the peer.
   *
   * @exception IOException This exception is thrown if the multicast group
   * cannot be joined. <p>
  */
  public void 
    addPeer(SessionAddress peerAddress) throws IOException,
    InvalidSessionAddressException;
  /**
   * Removes a peer from the list of peers.
   * <p>If the peer is not in the list the method call is ignored.
   * @param peerAddress The unicast address pair (RTP transport address,
   * RTCP transport address) of the peer. <p>
   */
  public void 
    removePeer(SessionAddress peerAddress);

  /**
   * Removes all peers from the list of peers. <p>
   */
  public void 
    removeAllPeers();
  /**
   * Gets the list of peers.
   * 
   * @return The list of current peers in the form of a Vector of
   SessionAddress objects.
  */
  public Vector 
    getPeers();
  

}
  



